home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1997 August / Macworld (1997-08).dmg / Shareware World / Info / For Developers / InstallerMaker™ 4.0 Installer / Customizing InstallerMaker / Sample Code / Documentation / IM 3.0 Code Spec < prev    next >
Text File  |  1997-05-12  |  10KB  |  305 lines
  1. About IM Self-Extractor Customization & Other Technical Goop
  2. ============================================================
  3.  
  4. Revised 94.12.31
  5. Raymond Lau
  6.  
  7. Revised 95.08.03
  8. Rob Thorne (RMT)
  9.  
  10.  
  11. A technical memorandum.
  12.  
  13. Copyright © 1990-97, Aladdin Systems, Inc.  All Rights Reserved.
  14.  
  15. ************************************************************************
  16.  
  17. InstallerMaker Extensions
  18. --------------------------
  19.  
  20. The IM Product Installer supports execution of code resources during installation.  All such
  21. atoms are strictly optional.
  22.  
  23. Note 1 -- when these atoms are called, the current resource file will be set to
  24. the self-extractor and should be maintained.
  25.  
  26. Note 2 -- 68k code rsrcs are assumed.  If you want to write PPC code, create an
  27. accelerated rsrc.
  28.  
  29. Note 3 -- Please be sure to see the Destinations Extensions documentation.  The
  30. ILoc atom is documented therein.
  31.  
  32.  
  33. refcon field
  34. ============
  35. Starting with IM 3.0, all atoms will be called with a refcon field which initially
  36. points to an unsigned long with the value zero.  Any atom may set the pointed to
  37. value to whatever it desires.  The pointed to value will be maintained in calls to
  38. any other atom.
  39.  
  40.  
  41. Packages field
  42. ==============
  43.  
  44. The interpretation of packages for the code rsrcs is:
  45.  
  46. IM 2.0: packages should be interpreted as a 16 bit field.  Bit 0 is the lowest bit.
  47.  
  48. IM 3.0: packages should be interpreted as a 128 bit field.  packages[0] contains
  49.     bits 0-31 where 0 is the lowest bit.  packages[1] contains bits 32-63 where
  50.     32 is the lowest bit.  Similarly for packages[2] and packages[3].
  51.  
  52. packages is a bit mask where bit 0 set means std pkg, bit 1 set means pkg A,
  53.     bit 2 means B, etc.  For compatibility, a value of zero is synonymous with all
  54.     ones.
  55.     
  56. The packages field typically specifies the currently selected pkgs unless
  57. otherwise noted.
  58.  
  59. IMEnvironsRec field
  60. ===================
  61.  
  62. typedef struct {
  63.     unsigned long *packages;
  64.     short userVol;
  65.     long userDir;
  66.     short userSysVol;
  67.     long userSysDir;
  68. } IMEnvironsRec;
  69.  
  70. This structure is used by various atoms.
  71.  
  72. Unless otherwise noted, the meaning of the files is:
  73.  
  74. The packages field is documented above.
  75.  
  76. The userVol/userDir specifies the USF or USV.  In the latter case, userDir will
  77. be 2L.
  78.  
  79. The userSysVol/userSysDir specifies the potentially blessed folder on the user
  80. specified system vol, if the developer allows the user to make this choice.
  81. Otherwise, it specifies the blessed folder on the startup volume.
  82.  
  83.  
  84. IFst
  85. ====
  86.  
  87. IM 3.0 id = 256
  88.  
  89.     pascal short IFst (unsigned long *refcon)
  90.  
  91. 'IFst' is called immediately upon startup and after initializing several internal
  92. data structures but before any user interaction (such as the startup pict) occurs.
  93.  
  94. The IFst should return 0 on success or non-zero to abort.
  95.  
  96.  
  97.  
  98. IBeg
  99. ====
  100.  
  101. IM 1.0 id = 0 [*** NO LONGER SUPPORTED IN 3.0 ***]
  102.  
  103.     pascal short IBeg(unsigned char *pw)
  104.  
  105. IM 2.0 id = 128 [for compat only]
  106.     
  107.     pascal short IBeg(unsigned char *pw)
  108.     
  109. IM 3.0 id = 256
  110.  
  111.     pascal short IBeg(unsigned char *pw,unsigned long *refcon)
  112.  
  113.  
  114. If an 'IBeg' rsrc exists, it will be called right after showing the splash screens
  115. but before prompting the user for the destination.
  116.  
  117. The pw argument is only relevant in the case of an encrypted SEA.  A zero length
  118. pascal string is passed in.  The IBeg may choose to return a PW in it and if correct,
  119. that PW will be used instead of prompting the user.
  120.  
  121. The IBeg should return 0 on success or non-zero to abort.
  122.  
  123.  
  124.  
  125.  
  126. ICnd
  127. ====
  128.  
  129. To support custom conditions, for each top level item, a call will be made to an 'ICnd'
  130. resource if it exists.  This resource will be passed the 3 custom conditions flags.
  131. Flag 1 will be bit 0, flag 2 will be bit 1, and flag 3 will be bit 2.  The resource
  132. will be called as:
  133.  
  134. IM 1.0 id = 0:  [*** NO LONGER SUPPORTED IN 3.0 ***]
  135.  
  136.     pascal short ICnd(short flags);
  137.  
  138. IM 2.0 id = 128: [compat only]
  139.  
  140.     pascal short ICnd(short flags,unsigned short packages);
  141.  
  142. IM 3.0 id = 256:
  143.  
  144.     pascal short ICnd(short flags,unsigned long *packages,unsigned long *refcon);
  145.  
  146.  
  147. The atom should return 0 if the item SHOULD be installed and 1 if the item SHOULD NOT.
  148. Note that the ICnd is more higher level than the IMid.  Information returned by the ICnd
  149. will be used in size computations, etc.  (Bec. of the possibility of segmented
  150. archives, we may not have access to more extensive info like file names, etc.)
  151.  
  152.  
  153. IPkg
  154. ====
  155.  
  156. IM 3.0 id = 256:
  157.  
  158.     pascal void IPkg(unsigned long *packages,unsigned long *refcon);
  159.     
  160. The IPkg atom is the package availability atom.  It should RETURN in packages
  161. which packages should be made unavailable to the user given the current machine
  162. configuration, etc.  By default, no packages are made unavailable.  A zero
  163. bit indicates that a package should be made unavailable.
  164.  
  165. The IPkg atom is ONLY used in custom install.  Note that the IPkg can only
  166. exclude packages by making them unavailable.  That is, if the package
  167. conditions make a package unavailable, the IPkg cannot change this.  It can
  168. only make packages which are available given package conditions unavailable.
  169. Also, the IPkg cannot make the standard package unavailable.  If there's a
  170. standard package defined, then it is always available.
  171.  
  172. Note that it is possible to not have a standard package defined, in which case
  173. the installer will only have custom install, no simple install.
  174.  
  175.  
  176.  
  177. IMid
  178. ====
  179.  
  180. Before each file/folder is unstuffed, a call will be made to an 'IMid' resource if it
  181. exists.  This resource will be called BEFORE checking to see if an existing item
  182. exists, if an existing item is newer.  However, it will be done AFTER checking
  183. for other conditions such as presence of color, system version, etc.  It will be
  184. called as a pascal function:
  185.  
  186. IM 1.0 id = 0: [*** NO LONGER SUPPORTED IN 3.0 ***]
  187.  
  188.     pascal short IMid(short userVol,long userDir,
  189.                         short *destVol,long *destDir,
  190.                         short isFolder,
  191.                         char *name,
  192.                         unsigned long creationDate,
  193.                         unsigned long modificationDate,
  194.                         OSType type,OSType creator);
  195.  
  196. IM 2.0 id = 128: [for compat only]
  197.  
  198.     pascal short IMid(short userVol,long userDir,
  199.                         short *destVol,long *destDir,
  200.                         short isFolder,
  201.                         char *name,
  202.                         unsigned long creationDate,
  203.                         unsigned long modificationDate,
  204.                         OSType type,OSType creator,
  205.                         unsigned short packages,
  206.                         short after);
  207.  
  208. IM 3.0 id = 256:
  209.  
  210.     pascal short IMid(    IMEnvironsRec *environ,
  211.                         short *destVol,long *destDir,
  212.                         short isFolder,
  213.                         char *name,
  214.                         unsigned long creationDate,
  215.                         unsigned long modificationDate,
  216.                         OSType type,OSType creator,
  217.                         short after,short tag,unsigned long *refcon);
  218.  
  219.  
  220. environ is as expected.
  221. destVol/destDir will be the current destination vol/dir.
  222. isFolder will be true if the item is a folder.
  223. name is the name of the item (pascal string).
  224. creationDate/modificationDate are the obvious things as are type/creator except
  225.     of course that type/creator are valid only if not isFolder.
  226. after (new to 2.0+) -- The IMid is now called both BEFORE an item is installed and AFTER.
  227.     after will be TRUE if this is the AFTER call. Note that changing destVol,destDir,name
  228.     in an AFTER call accomplishes nothing.
  229. tag (new to 3.0+) will be the 2 byte user settable tag associated with each item.
  230.  
  231. You should return 0 to continue with installation of this item,1 to skip it,
  232.     2 to cancel.
  233. You may modify destVol, destDir and name.
  234.  
  235.  
  236.  
  237. IEnd
  238. ====
  239.  
  240. At the end of installation, a call will be made to an 'IEnd' resource if it
  241. exists..
  242.  
  243. IM 1.0 id = 0 [*** NO LONGER SUPPORTED IN 3.0 ***]
  244.  
  245.     pascal short IEnd(short abort,short vol,long dir,char *name)
  246.  
  247. IM 2.0 id = 128 [for compat only]
  248.     
  249.     pascal short IEnd(short abort,short vol,long dir,char *name,
  250.                         unsigned short packages)
  251.     
  252. IM 3.0 id = 256
  253.     
  254.     pascal short IEnd(short abort,IMEnvironsRec *environ,
  255.                         short *restartFlag,unsigned long *refcon)
  256.  
  257. abort will be non-zero if installation was aborted.
  258.  
  259. environ is as expected.  **NOTE** that this differs from 3.0 in that the
  260.     userVol/userDir will now always be the actual userVol/userDir.  Before
  261.     we passed the vol/parID/name of the USF or vol/2L/zero length string of
  262.     the USV.  For reference, the old info is given below under [Pre 3.0].
  263.     This change makes the IEnd's conventions match those of the other atoms.
  264.  
  265. restartFlag indicates whether the current installation was set to trigger a
  266.     system restart.  The atom may change this but it is responsible for any
  267.     UI inconsistencies.
  268.  
  269. The atom should return 0 on sucess, non-zero to abort.
  270.  
  271. [Pre 3.0]
  272.  
  273. vol/dir/name will contain the user specified folder directory.  If a volume was
  274. specified, then vol will be that volume and name will be a zero length string.
  275. If neither a user specified folder nor volume was used, then vol,dir will be
  276. zero and name will be a zero length string.
  277.  
  278.  
  279. ----------------------------------------------------------------------------------------
  280.  
  281.  
  282.  
  283. For the Select Existing USF dialog, the New folder 2051 CNTL is now localizable.
  284. The refCon field is interpreted as follows:
  285.     Zero -- if first character is not a space, the END of the title drawn is the right
  286.                                 edge of the SICN.
  287.                     if first character is a space, the pen location of the first character drawn
  288.                                 is the left edge of the SICN.
  289.     Positive -- the refCon is interpreted as an absolute offset from the left edge of the
  290.                                 controlRect to the left edge of the SICN.
  291.     Negative -- the refCon is interpreted as an absolute offset from the left edge of the
  292.                                 controlRect to the right edge of the SICN.
  293.  
  294.  
  295. ----------------------------------------------------------------------------------------
  296.  
  297. Technical Notes:
  298.  
  299. When there is more than one file, all files are unstuffed into a new folder and
  300. any conflicting names will be automatically overwritten.  (You shouldn't have 2
  301. things w/the same name in an installation scenario anyway!)
  302.  
  303. In the Join SEA, when the next segment is sought, the root and then the desktop of
  304. all online volumes are checked first.  Then the user is prompted for a disk.
  305.